﻿#region Copyright Statement
//  ------------------------------------------------------------------------------
//  
//    This file is part of The Streambolics Library.
//    Copyright © 2005-2009, Stephan Leclercq & Streambolics
//    All rights reserved.
//  
//    The Streambolics Library is free software; you can redistribute it and/or modify
//    it under the terms of the GNU General Public License as published by
//    the Free Software Foundation; either version 2 of the License, or
//    (at your option) any later version.
//  
//    The Streambolics Library is distributed in the hope that it will be useful,
//    but WITHOUT ANY WARRANTY; without even the implied warranty of
//    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//    GNU General Public License for more details.
//  
//    You should have received a copy of the GNU General Public License
//    along with Streambolics; if not, write to the Free Software
//    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
//  
//  ------------------------------------------------------------------------------
#endregion

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace Streambolics
{
    /// <summary>
    ///     An object that is able to create messages to be transmitted
    ///     to other objects (<i>peers</i>) as a stream of bytes.
    /// </summary>
    /// <remarks><para>
    ///     Message Producers are poll based, ie they do not explicitly
    ///     trigger an event when there is something to send. A producer
    ///     is free to do so, but there is currently no defined interface
    ///     for that purpose.
    /// </para><para>
    ///     Most message producers are polled from a background task that will
    ///     forward the produced messages to other peers (message consumers.)
    /// </para><para>
    ///     Most message producers should be implemented as computing
    ///     modules.
    /// </para></remarks>

    public interface IMessageProducer
    {
        /// <summary>
        ///     Produce a new message.
        /// </summary>
        /// <remarks><para>
        ///     Message producers are not allowed to wait for a message to
        ///     arrive. If no message is available, the method must return
        ///     immediately.
        /// </para><para>
        ///     Message producers should normally wait for acknowledgement
        ///     from the peer. The acknowledgement is likely to be received
        ///     as an input message, so most IMessageProducer objects also
        ///     implement IMessageConsumer.
        /// </para></remarks>
        /// <returns>
        ///     The message to be sent to the peer, or null if there is
        ///     no message to be sent.
        /// </returns>

        byte[] ProduceMessage ();

    }
}
